

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">

    <title>README - LiterateCS</title>

	<link rel="icon" type="image/x-icon" href="images/favicon.ico">
    <link rel="stylesheet" href="bootstrap/css/readable/bootstrap.min.css" />
<link rel="stylesheet" href="font-awesome/css/font-awesome.min.css">
<link rel="stylesheet" href="sidebar/sidebar.min.css" />
<link rel="stylesheet" href="css/book.min.css" />
<link rel="stylesheet" href="syntax-highlight/solarized-light.min.css" />
<link rel="stylesheet" href="mermaid/mermaid.css" />

</head>

<body>
    
    <nav class="navbar navbar-inverse navbar-fixed-top">
        <div class="container">
            <div class="navbar-header">
                <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false" aria-controls="navbar">
                    <span class="sr-only">Toggle navigation</span>
                    <span class="icon-bar"></span>
                    <span class="icon-bar"></span>
                    <span class="icon-bar"></span>
                </button>
                <a class="navbar-brand" href="#sidebar-toggle" id="sidebar-toggle">
					<span>
						<img src="images/favicon.ico" height="24" class="hidden-sm hidden-xs" />
						<i id="sidebar-toggle-icon" class="hidden-md hidden-lg hidden-xl fa fa-angle-double-right" aria-hidden="true"></i>
						LiterateCS
					</span>
				</a>
            </div>
            <div id="navbar" class="navbar-collapse collapse">
                <ul class="nav navbar-nav">
                    <li><a href="index.html"><i class="fa fa-home" aria-hidden="true"></i> Home</a></li>
					<li><a href="https://github.com/johtela/LiterateCS"><i class="fa fa-github" aria-hidden="true"></i> GitHub Repository</a></li>
                    <li><a href="https://www.nuget.org/packages/LiterateCS/"><i class="fa fa-download" aria-hidden="true"></i> Download</a></li>
                    <li><a href="License.html">License</a></li>
                </ul>
            </div>
        </div>
    </nav>

    <div class="container">
        <div class="row">
            <div id="sidebar" class="col-md-3 hidden-sm hidden-xs">
                
        <div class="panel panel-default">
            <div class="panel-heading">
                <h4>On This Page</h4>
            </div>
            <div id="header-menu" class="panel-body main-menu">
                <ul></ul>
            </div>
        </div>  
        <div class="panel panel-default">
            <div class="panel-heading">
                <h4>Table of Contents</h4>
            </div>
            <div class="panel-body main-menu">
                <ul>
	<li><a href="index.html">Home</a></li>
	<ul>
	</ul>
	<li><a href="Introduction.html">Introduction</a></li>
	<ul>
	</ul>
	<li><a href="LiterateCS/Options.html">Command Line Options</a></li>
	<ul>
	</ul>
	<li><a href="LiterateCS/Program.html">Main Program</a></li>
	<ul>
	</ul>
	<li><a href="LiterateCS/SplitPath.html">SplitPath Structure</a></li>
	<ul>
	</ul>
	<li><a href="LiterateCS/Weaver.html">Document Weaver</a></li>
	<ul>
	</ul>
	<li><a href="LiterateCS/MdWeaver.html">Markdown Weaver</a></li>
	<ul>
	</ul>
	<li><a href="LiterateCS/HtmlWeaver.html">HTML Weaver</a></li>
	<ul>
	</ul>
	<li><a href="LiterateCS/TocManager.html">TOC Manager</a></li>
	<ul>
	</ul>
	<li><a href="LiterateCS/BlockList.html">Source Blocks</a></li>
	<ul>
	</ul>
	<li><a href="LiterateCS/Macro.html">Macros</a></li>
	<ul>
	</ul>
	<li><a href="LiterateCS/BlockBuilder.html">Block Builder</a></li>
	<ul>
	</ul>
	<li><a href="LiterateCS/HtmlBlockBuilder.html">HTML Block Builder</a></li>
	<ul>
	</ul>
	<li><a href="LiterateCS/HtmlGenerator.html">HTML Generation</a></li>
	<ul>
	</ul>
	<li>Themes</li>
	<ul>
<ul>
	<li><a href="LiterateCS.Theme/DirHelpers.html">Directory Utilities</a></li>
	<ul>
	</ul>
	<li><a href="LiterateCS.Theme/Toc.html">Table of Contents Classes</a></li>
	<ul>
	</ul>
	<li><a href="LiterateCS.Theme/PageParams.html">Page Parameters</a></li>
	<ul>
	</ul>
	<li><a href="LiterateCS.Theme/Theme.html">Theme Base Class</a></li>
	<ul>
	</ul>
	<li><a href="LiterateCS.Theme/LiterateException.html">Reporting Errors</a></li>
	<ul>
	</ul>
</ul>
	</ul>
	<li><a href="FrontMatter.html">Front Matter</a></li>
	<ul>
	</ul>
	<li><a href="TableOfContents.html">Table of Contents File</a></li>
	<ul>
	</ul>
	<li><a href="TipsAndTricks.html">Tips &amp; Tricks</a></li>
	<ul>
	</ul>
	<li><a href="License.html">License</a></li>
	<ul>
	</ul>
	<li><a href="README.html" class="selected">README</a></li>
	<ul>
	</ul>
	<li><a href="Installation.html">Installation</a></li>
	<ul>
	</ul>
</ul>
            </div>
        </div>

            </div>
			<div id="contentarea" class="col-md-9 col-sm-12 col-sm-push-0 col-xs-12 col-xs-push-0">
				<ul class="pager">
	<li class="previous"><a href="License.html">Previous: License</a></li>
	<li class="next"><a href="Installation.html">Next: Installation</a></li>
</ul>
				<div id="static-content" class="markdown">
					<p><a href="https://ci.appveyor.com/project/johtela/literatecs"><img src="https://ci.appveyor.com/api/projects/status/ah34q0i74rjanqpf?svg=true" alt="Build status" /></a>
<a href="https://www.nuget.org/packages/LiterateCS"><img src="https://img.shields.io/nuget/v/LiterateCS.svg" alt="NuGet Version" /></a></p>
<h1 id="literate-programming-in-c-and.net-core">Literate Programming in C# and .NET Core</h1>
<p>LiterateCS is a <a href="https://en.wikipedia.org/wiki/Literate_programming">Literate Programming</a> tool that produces clear,
professional-looking documentation automatically from your C# projects.
It parses C# code files and extracts <a href="https://en.wikipedia.org/wiki/Markdown">markdown</a> documentation from
comments. Alternatively you can write your documentation in separate
markdown files and interleave pieces of code in them by referring to
C# regions. LiterateCS can then create either a simple markdown output
that you can upload to your project's <a href="https://help.github.com/articles/about-github-wikis/">wiki</a> pages, or it can generate a
full-blown static web site that you can host in <a href="https://pages.github.com/">GitHub Pages</a>.</p>
<p>The idea of literate programming differs from the usual way of thinking
about technical documentation. Instead of documentation being an afterthough
which is taken care of after the project is done, literate programming encourages
you to document your code while you are writing it. Also, you don't write your
documentation as an API reference like with <a href="https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/xml-documentation-comments">xmldoc comments</a>, but rather
like text of an essay, explaining the things that need explaining and skipping
the obvious parts.</p>
<p>To get an idea about how this works in practice, refer to the literate
documentation created from this project. It can be found at:</p>
<p><strong><a href="https://johtela.github.io/LiterateCS/">https://johtela.github.io/LiterateCS/</a></strong></p>
<p>Other examples of documentation created with LiterateCS can be found at:</p>
<ul>
<li><a href="https://johtela.github.io/ExtensionCord/">https://johtela.github.io/ExtensionCord/</a></li>
<li><a href="https://johtela.github.io/LinqCheck/">https://johtela.github.io/LinqCheck/</a></li>
</ul>
<h2 id="quickstart">Quickstart</h2>
<p>To create your first literate program install first the <code>literatecs</code> tool
with command line:</p>
<pre><code>&gt; dotnet tool install -g literatecs
</code></pre>
<p>Then install the project template.</p>
<pre><code>&gt; dotnet new -i LiterateCS.Templates.LiterateLib.CSharp
</code></pre>
<p>After that create a new directory and the project skeleton.</p>
<pre><code>&gt; mkdir MyLiteratePony
&gt; cd MyLiteratePony
&gt; dotnet new literatelib
</code></pre>
<p>You should now have files for your class library created. You can
build the project with.</p>
<pre><code>&gt; dotnet build
</code></pre>
<p>To check what you got, you can open your project in <a href="https://code.visualstudio.com/">Visual Studio Code</a>
(this step is optional).</p>
<pre><code>&gt; code .
</code></pre>
<p>You should see the following project structure.</p>
<p><img src="docs/images/LiterateLibInVSCode.png" alt="...VSCode screenshot..." /></p>
<p>Finally you can create the documentation from your project with:</p>
<pre><code>&gt; literatecs
</code></pre>
<p>To see the generated documentation open the <code>docs/index.html</code> page in a web browser.</p>
<p><img src="docs/images/DocsForLiterateLib.png" alt="...Generated docs in browser..." /></p>
<h2 id="download-and-installation">Download and Installation</h2>
<p>The project was initially written for .NET Framework, but I recently
modified it to target <a href="https://www.microsoft.com/net/download/dotnet-core/2.1#sdk-2.1.300">.NET Core 2.1</a>. It is available in <a href="https://nuget.org">https://nuget.org</a>
as an <a href="https://docs.microsoft.com/en-us/dotnet/core/tools/global-tools">.NET Core global tool</a>.</p>
<p>See the <a href="https://johtela.github.io/LiterateCS/Installation.html">installation instructions</a> for more details. Documentation of the
command line options and usage examples can be found <a href="https://johtela.github.io/LiterateCS/LiterateCS/Options.html">here</a>.</p>
<h2 id="bug-reports-feedback">Bug Reports &amp; Feedback</h2>
<p>If you find a bug or want to suggest a feature, you can submit an <a href="https://github.com/johtela/LiterateCS/issues">issue</a>.</p>
<p>If you want to contribute to the development, let me know. All help is appreciated.</p>

				</div>
				<ul class="pager">
	<li class="previous"><a href="License.html">Previous: License</a></li>
	<li class="next"><a href="Installation.html">Next: Installation</a></li>
</ul>
			</div>
        </div>
    </div>
    
    <footer class="panel-footer text-center">
        <div align="center">Copyright © 2018 Tommi Johtela</div>
		<div align="right">
			<small>
				Documentation created with <a href="https://johtela.github.io/LiterateCS/">LiterateCS</a>.
			</small>
		</div>
    </footer>


    
    <script src="bootstrap/js/jquery.min.js"></script>
    <script src="bootstrap/js/bootstrap.min.js"></script>
    <script src="sidebar/sidebar.js"></script>
    <script src="syntax-highlight/syntax.js"></script>
    <script type="text/x-mathjax-config">
        MathJax.Hub.Config({
        extensions: ["jsMath2jax.js"]
        });
    </script>
    <script src='https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS_HTML'></script>
	<script src="mermaid/mermaid.min.js"></script>
	<script>mermaid.initialize({startOnLoad:true});</script>

</body>
</html>